
/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2018原创作者。
 *
 *根据Apache许可证2.0版许可（“许可证”）；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本：
 *
 *https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证进行的分发是在“按原样”的基础上进行的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证和
 *许可证下的限制。
 */

package org.springframework.validation;

import java.util.List;

import org.springframework.beans.PropertyAccessor;
import org.springframework.lang.Nullable;

/**
 * Stores and exposes information about data-binding and validation
 * errors for a specific object.
 *
 * <p>Field names can be properties of the target object (e.g. "name"
 * when binding to a customer object), or nested fields in case of
 * subobjects (e.g. "address.street"). Supports subtree navigation
 * via {@link #setNestedPath(String)}: for example, an
 * {@code AddressValidator} validates "address", not being aware
 * that this is a subobject of customer.
 *
 * <p>Note: {@code Errors} objects are single-threaded.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @see #setNestedPath
 * @see BindException
 * @see DataBinder
 * @see ValidationUtils
 */
/**
 *存储并公开有关数据绑定和验证的信息
 *特定对象的错误。
 *
 *<p>字段名称可以是目标对象的属性（例如“name”
 *绑定到客户对象时），或者在
 *子对象（例如“address.street”）。支持子树导航
 *via｛@link#setNestedPath（String）｝：例如
 *｛@code AddressValidator｝验证“地址”，而不知道
 *这是客户的一个子对象。
 *
 *＜p＞注意：｛@code Errors｝对象是单线程的。
 *
 *@作者罗德·约翰逊
 *@作者于尔根·霍勒
 *@参见#setNestedPath
 *@参见BindException
 *@参见DataBinder
 *@参见验证Utils
 */
public interface Errors {

	/**
	 * The separator between path elements in a nested path,
	 * for example in "customer.name" or "customer.address.street".
	 * <p>"." = same as the
	 * {@link org.springframework.beans.PropertyAccessor#NESTED_PROPERTY_SEPARATOR nested property separator}
	 * in the beans package.
	 */
	/**
	 *嵌套路径中的路径元素之间的分隔符，
	 *例如在“customer.name”或“customer.address.street”中。
	 *<p>“.”=与
	 *｛@link org.springframework.beans.PropertyAccessor#NESTED_PROPERTY_SPECRATOR嵌套属性分隔符｝
	 *在豆子包装中。
	 */
	String NESTED_PATH_SEPARATOR = PropertyAccessor.NESTED_PROPERTY_SEPARATOR;


	/**
	 * Return the name of the bound root object.
	 */
	/**
	 *返回绑定的根对象的名称。
	 */
	String getObjectName();

	/**
	 * Allow context to be changed so that standard validators can validate
	 * subtrees. Reject calls prepend the given path to the field names.
	 * <p>For example, an address validator could validate the subobject
	 * "address" of a customer object.
	 * @param nestedPath nested path within this object,
	 * e.g. "address" (defaults to "", {@code null} is also acceptable).
	 * Can end with a dot: both "address" and "address." are valid.
	 */
	/**
	 *允许更改上下文，以便标准验证器可以验证
	 *子树。Reject调用在字段名称的给定路径前加上前缀。
	 *＜p＞例如，地址验证器可以验证子对象
	 *客户对象的“地址”。
	 *@param nestedPath此对象内的嵌套路径，
	 *例如“address”（默认为“”，{@code null}也是可以接受的）。
	 *可以以句点结尾：“address”和“address.”都是有效的。
	 */
	void setNestedPath(String nestedPath);

	/**
	 * Return the current nested path of this {@link Errors} object.
	 * <p>Returns a nested path with a dot, i.e. "address.", for easy
	 * building of concatenated paths. Default is an empty String.
	 */
	/**
	 *返回此｛@link Errors｝对象的当前嵌套路径。
	 *<p>返回一个带点的嵌套路径，即“address.”，以便于
	 *连接路径的构建。默认值为空字符串。
	 */
	String getNestedPath();

	/**
	 * Push the given sub path onto the nested path stack.
	 * <p>A {@link #popNestedPath()} call will reset the original
	 * nested path before the corresponding
	 * {@code pushNestedPath(String)} call.
	 * <p>Using the nested path stack allows to set temporary nested paths
	 * for subobjects without having to worry about a temporary path holder.
	 * <p>For example: current path "spouse.", pushNestedPath("child") &rarr;
	 * result path "spouse.child."; popNestedPath() &rarr; "spouse." again.
	 * @param subPath the sub path to push onto the nested path stack
	 * @see #popNestedPath
	 */
	/**
	 *将给定的子路径推送到嵌套的路径堆栈中。
	 *<p>｛@link#popNestedPath（）｝调用将重置原始
	 *对应的前面的嵌套路径
	 *｛@code pushNestedPath（String）｝调用。
	 *<p>使用嵌套路径堆栈可以设置临时嵌套路径
	 *用于子对象，而不必担心临时路径保持器。
	 *<p>例如：当前路径“配偶.”，pushNestedPath（“孩子”）&rarr；
	 *结果路径“配偶.子女”；popNestedPath（）.rar；又是“配偶”。
	 *@param subPath要推送到嵌套路径堆栈上的子路径
	 *@参见#popNestedPath
	 */
	void pushNestedPath(String subPath);

	/**
	 * Pop the former nested path from the nested path stack.
	 * @throws IllegalStateException if there is no former nested path on the stack
	 * @see #pushNestedPath
	 */
	/**
	 *从嵌套路径堆栈中弹出前一个嵌套路径。
	 *如果堆栈上没有以前的嵌套路径，则@throws IllegalStateException
	 *@参见#pushNestedPath
	 */
	void popNestedPath() throws IllegalStateException;

	/**
	 * Register a global error for the entire target object,
	 * using the given error description.
	 * @param errorCode error code, interpretable as a message key
	 */
	/**
	 *为整个目标对象注册全局错误，
	 *使用给定的错误描述。
	 *@param errorCode错误代码，可解释为消息键
	 */
	void reject(String errorCode);

	/**
	 * Register a global error for the entire target object,
	 * using the given error description.
	 * @param errorCode error code, interpretable as a message key
	 * @param defaultMessage fallback default message
	 */
	/**
	 *为整个目标对象注册全局错误，
	 *使用给定的错误描述。
	 *@param errorCode错误代码，可解释为消息键
	 *@param defaultMessage回退默认消息
	 */
	void reject(String errorCode, String defaultMessage);

	/**
	 * Register a global error for the entire target object,
	 * using the given error description.
	 * @param errorCode error code, interpretable as a message key
	 * @param errorArgs error arguments, for argument binding via MessageFormat
	 * (can be {@code null})
	 * @param defaultMessage fallback default message
	 */
	/**
	 *为整个目标对象注册全局错误，
	 *使用给定的错误描述。
	 *@param errorCode错误代码，可解释为消息键
	 *@param errorArgs错误参数，用于通过MessageFormat绑定参数
	 *（可以是｛@code null｝）
	 *@param defaultMessage回退默认消息
	 */
	void reject(String errorCode, @Nullable Object[] errorArgs, @Nullable String defaultMessage);

	/**
	 * Register a field error for the specified field of the current object
	 * (respecting the current nested path, if any), using the given error
	 * description.
	 * <p>The field name may be {@code null} or empty String to indicate
	 * the current object itself rather than a field of it. This may result
	 * in a corresponding field error within the nested object graph or a
	 * global error if the current object is the top object.
	 * @param field the field name (may be {@code null} or empty String)
	 * @param errorCode error code, interpretable as a message key
	 * @see #getNestedPath()
	 */
	/**
	 *为当前对象的指定字段注册字段错误
	 *（关于当前嵌套路径，如果有的话），使用给定的错误
	 *描述。
	 *＜p＞字段名称可以是｛@code null｝或空字符串以表示
	 *当前对象本身，而不是其字段。这可能导致
	 *嵌套对象图或
	 *如果当前对象是顶部对象，则全局错误。
	 *@param field字段名称（可以是｛@code null｝或空字符串）
	 *@param errorCode错误代码，可解释为消息键
	 *@参见#getNestedPath（）
	 */
	void rejectValue(@Nullable String field, String errorCode);

	/**
	 * Register a field error for the specified field of the current object
	 * (respecting the current nested path, if any), using the given error
	 * description.
	 * <p>The field name may be {@code null} or empty String to indicate
	 * the current object itself rather than a field of it. This may result
	 * in a corresponding field error within the nested object graph or a
	 * global error if the current object is the top object.
	 * @param field the field name (may be {@code null} or empty String)
	 * @param errorCode error code, interpretable as a message key
	 * @param defaultMessage fallback default message
	 * @see #getNestedPath()
	 */
	/**
	 *为当前对象的指定字段注册字段错误
	 *（关于当前嵌套路径，如果有的话），使用给定的错误
	 *描述。
	 *＜p＞字段名称可以是｛@code null｝或空字符串以表示
	 *当前对象本身，而不是其字段。这可能导致
	 *嵌套对象图或
	 *如果当前对象是顶部对象，则全局错误。
	 *@param field字段名称（可以是｛@code null｝或空字符串）
	 *@param errorCode错误代码，可解释为消息键
	 *@param defaultMessage回退默认消息
	 *@参见#getNestedPath（）
	 */
	void rejectValue(@Nullable String field, String errorCode, String defaultMessage);

	/**
	 * Register a field error for the specified field of the current object
	 * (respecting the current nested path, if any), using the given error
	 * description.
	 * <p>The field name may be {@code null} or empty String to indicate
	 * the current object itself rather than a field of it. This may result
	 * in a corresponding field error within the nested object graph or a
	 * global error if the current object is the top object.
	 * @param field the field name (may be {@code null} or empty String)
	 * @param errorCode error code, interpretable as a message key
	 * @param errorArgs error arguments, for argument binding via MessageFormat
	 * (can be {@code null})
	 * @param defaultMessage fallback default message
	 * @see #getNestedPath()
	 */
	/**
	 *为当前对象的指定字段注册字段错误
	 *（关于当前嵌套路径，如果有的话），使用给定的错误
	 *描述。
	 *＜p＞字段名称可以是｛@code null｝或空字符串以表示
	 *当前对象本身，而不是其字段。这可能导致
	 *嵌套对象图或
	 *如果当前对象是顶部对象，则全局错误。
	 *@param field字段名称（可以是｛@code null｝或空字符串）
	 *@param errorCode错误代码，可解释为消息键
	 *@param errorArgs错误参数，用于通过MessageFormat绑定参数
	 *（可以是｛@code null｝）
	 *@param defaultMessage回退默认消息
	 *@参见#getNestedPath（）
	 */
	void rejectValue(@Nullable String field, String errorCode,
			@Nullable Object[] errorArgs, @Nullable String defaultMessage);

	/**
	 * Add all errors from the given {@code Errors} instance to this
	 * {@code Errors} instance.
	 * <p>This is a convenience method to avoid repeated {@code reject(..)}
	 * calls for merging an {@code Errors} instance into another
	 * {@code Errors} instance.
	 * <p>Note that the passed-in {@code Errors} instance is supposed
	 * to refer to the same target object, or at least contain compatible errors
	 * that apply to the target object of this {@code Errors} instance.
	 * @param errors the {@code Errors} instance to merge in
	 */
	/**
	 *将给定｛@code errors｝实例中的所有错误添加到此
	 *｛@code Errors｝实例。
	 *<p>这是一种避免重复{@code-reject（..）}的方便方法
	 *调用将｛@code Errors｝实例合并到另一个实例
	 *｛@code Errors｝实例。
	 *＜p＞请注意，传入的｛@code Errors｝实例应该是
	 *引用相同的目标对象，或者至少包含兼容的错误
	 *应用于此｛@code Errors｝实例的目标对象。
	 *@param错误要合并的｛@code errors｝实例
	 */
	void addAllErrors(Errors errors);

	/**
	 * Return if there were any errors.
	 */
	/**
	 *如果有任何错误，请返回。
	 */
	boolean hasErrors();

	/**
	 * Return the total number of errors.
	 */
	/**
	 *返回错误总数。
	 */
	int getErrorCount();

	/**
	 * Get all errors, both global and field ones.
	 * @return a list of {@link ObjectError} instances
	 */
	/**
	 *获取所有错误，包括全局错误和字段错误。
	 *@返回｛@link ObjectError｝实例的列表
	 */
	List<ObjectError> getAllErrors();

	/**
	 * Are there any global errors?
	 * @return {@code true} if there are any global errors
	 * @see #hasFieldErrors()
	 */
	/**
	 *是否存在任何全局错误？
	 *@return｛@code true｝如果存在任何全局错误
	 *@参见#hasFieldErrors（）
	 */
	boolean hasGlobalErrors();

	/**
	 * Return the number of global errors.
	 * @return the number of global errors
	 * @see #getFieldErrorCount()
	 */
	/**
	 *返回全局错误数。
	 *@返回全局错误数
	 *@参见#getFieldErrorCount（）
	 */
	int getGlobalErrorCount();

	/**
	 * Get all global errors.
	 * @return a list of {@link ObjectError} instances
	 */
	/**
	 *获取所有全局错误。
	 *@返回｛@link ObjectError｝实例的列表
	 */
	List<ObjectError> getGlobalErrors();

	/**
	 * Get the <i>first</i> global error, if any.
	 * @return the global error, or {@code null}
	 */
	/**
	 *获取<i>第一个</i>全局错误（如果有）。
	 *@返回全局错误，或｛@code null｝
	 */
	@Nullable
	ObjectError getGlobalError();

	/**
	 * Are there any field errors?
	 * @return {@code true} if there are any errors associated with a field
	 * @see #hasGlobalErrors()
	 */
	/**
	 *是否存在任何字段错误？
	 *@return｛@code true｝如果有任何与字段相关联的错误
	 *@参见#hasGlobalErrors（）
	 */
	boolean hasFieldErrors();

	/**
	 * Return the number of errors associated with a field.
	 * @return the number of errors associated with a field
	 * @see #getGlobalErrorCount()
	 */
	/**
	 *返回与字段关联的错误数。
	 *@返回与字段相关联的错误数
	 *@参见#getGlobalErrorCount（）
	 */
	int getFieldErrorCount();

	/**
	 * Get all errors associated with a field.
	 * @return a List of {@link FieldError} instances
	 */
	/**
	 *获取与字段关联的所有错误。
	 *@return｛@link FieldError｝实例列表
	 */
	List<FieldError> getFieldErrors();

	/**
	 * Get the <i>first</i> error associated with a field, if any.
	 * @return the field-specific error, or {@code null}
	 */
	/**
	 *获取与字段相关联的<i>第一个</i>错误（如果有的话）。
	 *@返回字段特定的错误，或｛@code null｝
	 */
	@Nullable
	FieldError getFieldError();

	/**
	 * Are there any errors associated with the given field?
	 * @param field the field name
	 * @return {@code true} if there were any errors associated with the given field
	 */
	/**
	 *是否有任何与给定字段相关的错误？
	 *@param字段字段名称
	 *@return｛@code true｝如果有任何与给定字段相关的错误
	 */
	boolean hasFieldErrors(String field);

	/**
	 * Return the number of errors associated with the given field.
	 * @param field the field name
	 * @return the number of errors associated with the given field
	 */
	/**
	 *返回与给定字段关联的错误数。
	 *@param字段字段名称
	 *@返回与给定字段相关联的错误数
	 */
	int getFieldErrorCount(String field);

	/**
	 * Get all errors associated with the given field.
	 * <p>Implementations should support not only full field names like
	 * "name" but also pattern matches like "na*" or "address.*".
	 * @param field the field name
	 * @return a List of {@link FieldError} instances
	 */
	/**
	 *获取与给定字段关联的所有错误。
	 *<p>实现不仅应支持诸如
	 *“name”，还有“na*”或“address.*”等模式匹配。
	 *@param字段字段名称
	 *@return｛@link FieldError｝实例列表
	 */
	List<FieldError> getFieldErrors(String field);

	/**
	 * Get the first error associated with the given field, if any.
	 * @param field the field name
	 * @return the field-specific error, or {@code null}
	 */
	/**
	 *获取与给定字段相关联的第一个错误（如果有的话）。
	 *@param字段字段名称
	 *@返回字段特定的错误，或｛@code null｝
	 */
	@Nullable
	FieldError getFieldError(String field);

	/**
	 * Return the current value of the given field, either the current
	 * bean property value or a rejected update from the last binding.
	 * <p>Allows for convenient access to user-specified field values,
	 * even if there were type mismatches.
	 * @param field the field name
	 * @return the current value of the given field
	 */
	/**
	 *返回给定字段的当前值，或者
	 *bean属性值或来自上次绑定的被拒绝的更新。
	 *<p>允许方便地访问用户指定的字段值，
	 *即使存在类型不匹配。
	 *@param字段字段名称
	 *@返回给定字段的当前值
	 */
	@Nullable
	Object getFieldValue(String field);

	/**
	 * Return the type of a given field.
	 * <p>Implementations should be able to determine the type even
	 * when the field value is {@code null}, for example from some
	 * associated descriptor.
	 * @param field the field name
	 * @return the type of the field, or {@code null} if not determinable
	 */
	/**
	 *返回给定字段的类型。
	 *<p>实现甚至应该能够确定类型
	 *当字段值为{@code-null}时，例如来自
	 *关联描述符。
	 *@param字段字段名称
	 *@返回字段的类型，或者｛@code null｝如果不可确定
	 */
	@Nullable
	Class<?> getFieldType(String field);

}
